home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audiofile / AFreadmisc.z / AFreadmisc
Encoding:
Text File  |  2002-10-03  |  9.7 KB  |  133 lines
  1.  
  2.  
  3.  
  4. aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc((((3333ddddmmmm))))                                                aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      afReadMisc, afWriteMisc, afSeekMisc - read from / write to / move logical
  10.      read/write pointer for data in a miscellaneous chunk in an audio file
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiiooooffffiiiilllleeee....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc((((ccccoooonnnnsssstttt AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee ffffiiiilllleeee,,,, iiiinnnntttt mmmmiiiisssscccciiiidddd,,,,
  16.                                   vvvvooooiiiidddd ****bbbbuuuuffff,,,, iiiinnnntttt nnnnbbbbyyyytttteeeessss))))
  17.  
  18.      iiiinnnntttt aaaaffffWWWWrrrriiiitttteeeeMMMMiiiisssscccc((((ccccoooonnnnsssstttt AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee ffffiiiilllleeee,,,, iiiinnnntttt mmmmiiiisssscccciiiidddd,,,,
  19.                                   vvvvooooiiiidddd ****bbbbuuuuffff,,,, iiiinnnntttt nnnnbbbbyyyytttteeeessss))))
  20.  
  21.      iiiinnnntttt aaaaffffSSSSeeeeeeeekkkkMMMMiiiisssscccc((((ccccoooonnnnsssstttt AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee ffffiiiilllleeee,,,, iiiinnnntttt cccchhhhuuuunnnnkkkkiiiidddd,,,,
  22.                                   iiiinnnntttt ooooffffffffbbbbyyyytttteeeessss))))
  23.  
  24. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  25.      _f_i_l_e     expects the AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure for the audio file from or to
  26.               which you want to read or write data.  This structure is
  27.               returned by aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm) call.
  28.  
  29.      _m_i_s_c_i_d   expects an integer which identifies the miscellaneous data chunk
  30.               you want to read from or write to.
  31.  
  32.      _b_u_f      expects a pointer to a buffer which will receive a copy of the
  33.               miscellaneous data from the file, or which contains the data you
  34.               want to transfer into the file.
  35.  
  36.      _n_b_y_t_e_s   is the number of bytes of data you want to read from the file
  37.               into _b_u_f or from _b_u_f into the file (beginning at the current
  38.               position of _f_i_l_e'_s logical read pointer for the data in _m_i_s_c_i_d).
  39.  
  40.      _o_f_f_b_y_t_e_s specifies a nonnegative offset into the data area for _c_h_u_n_k_i_d
  41.               (the offset should be less than total size of the data area).
  42.  
  43. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  44.      aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc(((()))) returns the number of bytes actually read from the
  45.      miscellaneous chunk into _b_u_f.  aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc(((()))) will not let you read beyond
  46.      the end of the chunk's data area.  The return value is greater than or
  47.      equal to 0 except in cases of error.  It is an error to call aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc(((())))
  48.      on a miscellaneous chunk of size zero.
  49.  
  50.      aaaaffffWWWWrrrriiiitttteeeeMMMMiiiisssscccc(((()))) returns the number of bytes actually written to the
  51.      miscellaneous chunk.  aaaaffffWWWWrrrriiiitttteeeeMMMMiiiisssscccc(((()))) will not let you write beyond the end
  52.      of the chunk's data area.  The return value is always greater than or
  53.      equal to 0 except in case of error, when -1 is returned.
  54.  
  55.      aaaaffffSSSSeeeeeeeekkkkMMMMiiiisssscccc(((()))) returns the new location of the logical read/write pointer
  56.      for the miscellaneous chunk, measured as an offset in bytes from the
  57.      beginning of the chunk's data area.  This value is always greater than or
  58.      equal to 0, and less than or equal to the total number of data bytes, as
  59.      reported by aaaaffffGGGGeeeettttMMMMiiiissssccccSSSSiiiizzzzeeee(3dm).
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc((((3333ddddmmmm))))                                                aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  75.      aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc(((()))) copies data from the specified miscellaneous of an audio
  76.      file to _b_u_f.  The _f_i_l_e structure maintains internally a logical read
  77.      pointer for each miscellaneous chunk in the file.  This allows you to
  78.      read and write miscellaneous data (e.g., MIDI system exclusive data) from
  79.      a file in small pieces in separate calls.
  80.  
  81.      You call aaaaffffGGGGeeeettttMMMMiiiissssccccIIIIDDDDssss(3dm) to obtain the list of miscellaneous chunk ID's
  82.      for _f_i_l_e.  You call aaaaffffGGGGeeeettttMMMMiiiissssccccTTTTyyyyppppeeee(3dm) to figure out what types of
  83.      miscellaneous chunks you have (see the aaaaffffGGGGeeeettttMMMMiiiissssccccTTTTyyyyppppeeee(3dm) man page for
  84.      more information), and you call aaaaffffGGGGeeeettttMMMMiiiissssccccSSSSiiiizzzzeeee(3dm) to determine the total
  85.      number of bytes in each chunk.
  86.  
  87.      When a file is opened by aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm) or aaaaffffOOOOppppeeeennnnFFFFDDDD(3dm), the logical
  88.      read pointer for each miscellaneous data chunk is initialized to the
  89.      first data byte in the chunk.  On return from aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc(((()))), the chunk's
  90.      read pointer is automatically updated so that it points to the data byte
  91.      following the last one copied into _b_u_f.
  92.  
  93.      aaaaffffWWWWrrrriiiitttteeeeMMMMiiiisssscccc(((()))) transfers data from _b_u_f the specified miscellaneous chunk
  94.      of an audio file. The _f_i_l_e structure maintains an internal logical write
  95.      pointer for each miscellaneous chunk, so that you can write part of the
  96.      data for a chunk with one call to aaaaffffWWWWrrrriiiitttteeeeMMMMiiiisssscccc(((()))), and write more data
  97.      later with a second call.
  98.  
  99.      You call aaaaffffIIIInnnniiiittttMMMMiiiissssccccIIIIDDDDssss(3dm) to set the list of miscellaneous chunk ID's
  100.      for _f_i_l_e when it is opened.  You call aaaaffffIIIInnnniiiittttMMMMiiiissssccccTTTTyyyyppppeeee(3dm) to initialize
  101.      the types of miscellaneous chunks in the file (see the man page for
  102.      aaaaffffIIIInnnniiiittttMMMMiiiissssccccTTTTyyyyppppeeee(3dm) for more details), and you call aaaaffffIIIInnnniiiittttMMMMiiiissssccccSSSSiiiizzzzeeee(3dm)
  103.      to set the total number of data bytes allocated for each chunk.
  104.  
  105.      When an audio file is created by a call to aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm), the write
  106.      pointer for each miscellaneous chunk is initialized to the first data
  107.      byte in the chunk.  The data area for each chunk is initially filled with
  108.      0's. On return from aaaaffffWWWWrrrriiiitttteeeeMMMMiiiisssscccc(((()))), the logical write pointer for _m_i_s_c_i_d
  109.      is automatically updated so that it points to the data byte following the
  110.      last one copied from _b_u_f to the file. It is up to the application to fill
  111.      the data area of each chunk with consistent information (e.g., if you
  112.      don't use all the bytes you allocated for a MIDI chunk, fill the
  113.      remaining bytes with no-op messages).
  114.  
  115.      aaaaffffSSSSeeeeeeeekkkkMMMMiiiisssscccc allows you to reposition the logical read/write pointer for a
  116.      specified miscellaneous chunk inside an audio file.  For example, you can
  117.      move the read pointer for a MIDI data chunk in an AIFF/AIFF-C file to any
  118.      location within the MIDI data before calling aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc.  It is illegal
  119.      to move the logical read/write pointer to a position before the first
  120.      data byte of the specified chunk, or after the last data byte.
  121.  
  122. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  123.      afOpenFile(3dm), afInitMiscType(3dm), afInitMiscSize(3dm),
  124.      afGetMiscIDs(3dm)
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.